Amiga Plus 1996 #4

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Plus 1996 #4 / Amiga Plus CD - 1996 - No. 4.iso / pd / daten / abxcd_v1.0 / startup.doc < prev next >

Wrap

Text File | 1995-09-27 | 20KB | 578 lines

Startup.doc written by C. Dean September 1995. How To Run ABxCD from the Workbench ----------------------------------- Just double click on the ABxCD.b0 database icon. This starts up ABxCD in interactive mode. Standard output is re-directed to the file ABxCD.stdout. How To Run ABxCD from the CLI ----------------------------- ABxCD takes the following parameters:- ABxCD <command> <options> where <command> is one of:- createdb - to create the database files. buildhyperidx - to re-build the hypertext index. execfile - to execute a file of ABxCD commands. execicode - to execute some icode. rexx - to execute some icode and wait for arexx commands. create0S - to create a 0 dimensioned string variable. create1S - to create a 1 dimensioned string variable (table). create0L - to create a 0 dimensioned integer variable. create1L - to create a 1 dimensioned integer variable. deleterecs - to delete the records of a database table. deletevar - to delete a variable. get - to get a record from a database table. put - to put a record into a database table. getall - to get all records from a database table. putall - to put all records into a database table. putimage - to put an icon image into the database. populate - to populate a table with records. extend - to re-size a table. report - to report on the database variables. modifystructure - to add or delete fields in a table. checkdb - to verify database structures. compressdb - to reduce fragmentation within the database. and <options> are any of the following:- db=<dbname> - specifies the database name. ini=<filename> - specifies the initialisation file to use. info=<number> - sets info level ( 1, 2 or 3 ). icdiag=<number> - sets the icode diagnostic level. csmap=<name> - specified colour/style map to use. noautoflush - disable automatic disk database updates. compall - compile all screens and icode at startup. border=<number> - sets the border character of active forms. first=<formname> - specifies first form to display. fontname=<fontname> - specifies the font to use. fontsize=<fontsize> - specifies the font size to use. buffers=<number> - sets the number of 32k tdb buffers to use. keys=<number> - reserves space for icode literal names. strings=<number> - reserves space for icode strings. arrays=<number> - reserves space for icode arrays. procs=<number> - reserves space for icode procedures. cell=<number> - specifies a record number. cell=* - specifies all records. cell=+ - specifies next available record number. var=<varname> - specifies variable name. file=<filename> - specifies filename. icode=<icode> - specifies icode to be executed. contents=<searchstr> - specifies cell by first line contents. size=<number> - specifies record average size in bytes. If <command> is absent ABxCD runs in interactive mode, displaying the first form on the screen. Invoking ABxCD with no parameters is the normal way. The options:- ini=, noautoflush, compall, border=, buffers=, keys=, strings=, arrays=, procs=, csmap=, first=, fontname= and fontsize= are used when running interactively. The options:- ini=, buffers=, keys=, strings=, arrays=, procs=, icode=, file=, cell= and contents= are used when executing some icode (execicode and rexx commands). The db= option names the database files to use. The default is 'ABxCD' which uses the database files ABxCD.b0 and ABxCD.b1. The ini= option specifies an initialisation file which may contain further options. Only the options noautoflush, border=, buffers=, keys=, strings=, arrays=, procs=, csmap=, first=, fontname=, fontsize= are allowed in an initialisation file. If no ini= option is present, the file <dbname>.ini is used, if it exists. The csmap= option is to specify which colour/style map to use. If none is specified, the map named 'default' is used. These maps are records in the variable sys_colstyle. The border= option sets the ascii value of the character used as a border for the active form. The default is 32 (space). A value of 127 looks good on mono displays. The first= option specifies the name of the form to be displayed first. If omitted, the form called "first" is first displayed. The fontname= option specifies the font name to be used to display all text in ABxCD. Use with the fontsize= option. If omitted, the workbench font is used. Proportional spaced fonts are not allowed. The buffers= option is to set the number of 32k byte buffers for use with the tdb database. A larger value may improve performance. The keys= option reserves space for all icode defined names, also known as literals. The strings= option reserves space for the contents of all str type icode variables. The arrays= option reserves space for the contents of all array type icode variables. The procs= option reserves space for the contents of all proc type icode variables i.e. procedure bodies. Also known as dictionary space. Use the icode proc icspace() to find out how much of each type of space is being used and how much is available. If not otherwise specified, ABxCD runs with the following values:- buffers=6 keys=1000 strings=10000 arrays=500 procs=20000 which occupies 6*32768 + 1000*52 + 10000 + 500*4 + 20000*4 bytes. Running ABxCD Interactively --------------------------- To speed up the time it takes ABxCD to start up, the forms and their associated icode are not compiled at startup; instead they are compiled as required when the form is to be displayed. The compall option may be used to compile all forms and their icode at startup. It may take a second or two to compile the form and its associated icode. If the database is on a floppy disk, set the noautoflush option to disable the automatic flushing of changed data to disk every 2 seconds. Use the flush-buffers function (key ^U) to keep the disk up-to-date. If possible, an arexx port named ABxCD is setup and the facilities detailed under the rexx section below are available interactively. Details for the above commands ------------------------------ createdb -------- To create a database with a name mydb:- ABxCD createdb db=mydb This creates two files, mydb.b0 and mydb.b1, which are the database files. If the db= option is omitted, the database name defaults to ABxCD. buildhyperidx ------------- Whenever the hypertext help pages are modified or first installed, the hypertext index needs to be re-built. This is done by:- ABxCD buildhyperidx execfile -------- To speed up the getting and putting of many files into and from the database, these commands can be put into a file and executed using the execfile command. Only get, put, getall, putall, create0S, create1S, create0L, create1L, report, extend, deleterecs, deletevar and populate commands are allowed in a file that is executed using execfile. Example usage:- ABxCD execfile file=myfile where myfile contains:- ABxCD create1S var=sys_icode ABxCD put var=sys_icode cell=+ file=rep1.icode ABxCD put var=sys_icode cell=+ file=rep2.icode execicode --------- All icode is stored in the sys_icode variable. To compile and interpret a record in the sys_icode variable use:- ABxCD execicode contents=rep1 This assumes there is a record whose first line contains the string 'rep1'. The record may also be specified using the cell= option. The record usually only contains the procedure definitions; to execute some procedure use, for example:- ABxCD execicode contents=rep1 "icode=rep1( 67 );" Double quotes are required because of the spaces and semi-colon in the string (although neither spaces nor semi-colon is required here). Files may also be interpreted; use the file= option to specify the file to be executed. The first two lines of the file are ignored. For example:- ABxCD execicode icode=test("orders") file=test.ic If both a file and a record are specified, the record is interpreted first. The sys_icode record called "first" is always compiled and interpreted first. rexx ---- This command is identical to the execicode command, executing some icode in background then waiting for arexx commands on the port named ABxCD. The following arexx commands are supported:- QUIT COMPILE "record name" ICODE "icode procs" KEYVALUE keynumber KEYSTRING "string" Note that arexx commands are also handled in interactive mode and the icode proc icdorexx() issues synchronous arexx commands to other applications. Arexx programs that wish to call icode procs should be started from icode using:- system( "run rx myrexxprogram" ); The quit command causes ABxCD to terminate, but is ignored if running interactively. The compile command causes the record in the sys_icode variable to be compiled and interpreted if not previously compiled. The icode command causes the parameter string to be interpreted. Note that it is not possible to interprete icode while already interpreting icode. The arexx result string is the contents of an icode string which is defined by calling the icode proc icrexxresult(). The keyvalue and keystring commands can only be used when running interactively. Keyvalue places the decimal keynumber value in the input stream as though typed in by the user. Keystring places the string in the input stream. Note the following special values of keynumber that may be used:- 256-259: arrow keys up, down, left, right 260-263: shift arrow keys 264: help key 267: backtab key (shift tab) 268-277: F1 to F10 278-287: shift F1 to shift F10 create0S -------- To create a 0 dimensioned string variable, i.e. a table capable of storing only one record, use, for example:- ABxCD create0S var=picklist create1S -------- To create a 1 dimensioned string variable, i.e. a table capable of storing many records, use, for example:- ABxCD create1S var=sys_icode create0L -------- To create a 0 dimensioned integer variable, i.e. a 4 byte area capable of storing a single integer, use, for example:- ABxCD create0L var=order_number create1L -------- To create a 1 dimensioned integer variable, i.e. an array capable of storing many integers, use, for example:- ABxCD create1L var=sales_by_week deleterecs ---------- To delete the records in a 1 dimensioned string variable use:- ABxCD deleterecs var=sys_icode The cell 0 datafile structure record is not deleted. deletevar --------- To delete a variable use:- ABxCD deletevar var=sys_icode If the variable is a 1 dimensioned string then the variable must be empty, i.e. contain no records (apart from the cell 0 datafile structure record). Use deleterecs to delete all records in a string variable. get --- To get a record from a string variable, use, for example, either:- ABxCD get var=sys_icode cell=12 file=rep1.icode or ABxCD get var=sys_icode contents=rep1 file=rep1.icode The file rep1.icode is created or overwritten with the record contents. The contents= option identifies a record by the contents of its first field. In the above example, all records are searched for the string 'rep1' in the first field and, providing only one record matches, that record is used. If the file= option is omitted, the record contents are written to standard output. If the variable is of 0 dimension, the cell= and contents= options may be omitted. To get a series of records from the database, use, for example:- ABxCD get var=sys_icode cell=* file=rep999.icode The filename 'rep999.icode' is a template which must contain a number, in this case 999, which has upto 6 digits in it. All records in cells 0 to 999 are written to the files rep000.icode, rep001.icode, etc. No files are created for records that do not exist. Note that cell 0 contains a special record used for checking datafile structure. put --- To put a record into a string variable, use, for example, one of:- ABxCD put var=sys_icode cell=12 file=rep1.icode or ABxCD put var=sys_icode cell=+ file=rep1.icode or ABxCD put var=sys_icode contents=rep1 file=rep1.icode The file rep1.icode is read and its contents put into the database. The cell=+ option puts the record into the next available cell. Cells of previously deleted records are re-used. The contents= option is used to select a record to be overwritten. If the file= option is omitted, the record contents are read from standard input. If the variable is of 0 dimension, the cell= and contents= options may be omitted. No checking is performed on the contents of the record being put into the database; it is vital that the record conforms to the correct structure. To put a series of records into the database, use, for example:- ABxCD put var=sys_icode cell=* file=rep999.icode The filename 'rep999.icode' is a template which must contain a number, in this case 999, which has upto 6 digits in it. All the files rep000.icode, rep001.icode, etc. are read and put into the corresponding cells. Note that cell 0 contains a special record used for checking datafile structure. getall ------ To get all records of a string variable, use getall as follows:- ABxCD getall var=sys_icode file=x.x The file x.x is created and filled with all the records of the variable. Using getall is faster than using get cell=* since only one file is written. putall ------ To put all records back into a string variable, use putall as follows:- ABxCD putall var=sys_icode file=x.x The variable must exist and contain no records before using putall. The file must have been created using getall. putimage -------- To read an IFF ILBM or icon image and put it into the sys_image database variable use:- ABxCD putimage contents=name file=x.x The file is first checked to see if it is a valid IFF. The iffparse.library is required to read IFFs. If the file cannot be read as an IFF, the image taken from the file's unselected icon (.info file) is read. If the image has more than 8 colours only the first 3 bitplanes are read to produce an 8 colour image. The resulting image is stored in the sys_image 1 dimensioned string type variable in an internal format suitable for the icode proc ugdrawimage(). The contents name is used to identify the image. Any existing image in the sys_image variable with the same name is overwritten. If the file= parameter is omitted, any image with that name is deleted. The icode proc ugloadimage() does the same as putimage. populate -------- To generate random records, use extend then populate as follows:- ABxCD populate var=sys_icode cell=10000 file=template This reads the file template and generates records for cells 1 to 10000 of the 1 dimensioned string variable according to the template. The template file may contain any of the following special sequences:- %<d> - where <d> is a digit 1 to 6 - substitute next integer using <d> decimal places. %<c> - where <c> is a character 'a' to 'f' - substitute a random integer using 1 to 6 decimal places. %x - substitute a random character. Populate may also be used to delete all records in a variable. First create an empty file called 'empty' then use populate as follows:- ABxCD populate var=sys_icode cell=* file=empty extend ------ ABxCD automatically extends variables as required. When a table has to be extended, either because it needs more cells or because it needs more record space, it is copied within the database and given 25% more record space than currently occupied and upto 50% more cells than cells used. As a result of this copy, the database file itself may need to be extended. If a very large variable has to be extended several times, the database file will grow to at least three times the size of the large variable. The extend facility allows a 1 dimensioned string variable to be sized by the user so as to avoid the above problems and save the time that would be spent doing automatic extends. For example:- ABxCD extend var=sys_icode cell=10000 size=125 This extends the variable to allow for 10000 cells and provide record space for 10000 records each with an average size of 125 bytes. Note that using extend with cell=0 and size=0 shrinks the table to its smallest possible size but does not reduce the number of allocated cells. The compressdb command does alter the number of cells of variables it moves. report ------ To find out the names, cells in use, sizes etc. of all variables in the database use:- ABxCD report To get a list of the first field contents of all records in a variable use:- ABxCD report var=sys_icode cell=* The cell= option may be used to limit the number of cells reported. If this option is omitted, only the first 20 cells are reported. modifystructure --------------- This command is to allow changes to the field structure of the variables. The following rules apply:- a) If adding a non-scrolling field it must be placed before all scrolling fields. b) If adding a member of a scrolling field it must not have the 'F' (first scrolling) attribute. c) If adding a new scrolling area it must be placed after all fields. To add a data field in a variable use the following procedure:- a) Run ABxCD interactively. Using the system datafile forms under system maintainance, add a new subrecord entry for the new field and give it the attribute '+'. Exit ABxCD. b) Run ABxCD with the modifystructure command:- ABxCD modifystructure c) Run ABxCD interactively. Ignore the error 'addfield or delfield attr needs modifystructure' and others caused by this. Using the system datafile forms under system maintainance, remove the '+' attribute. Exit ABxCD. To delete a data field use the following procedure:- a) Run ABxCD interactively. Using the system datafile forms under system maintainance, give the field to be deleted the '-' attribute. Exit ABxCD. b) Run ABxCD with the modifystructure command:- ABxCD modifystructure c) Run ABxCD interactively. Ignore the error:- 'invalid data description change (...)' and others caused by it. Using the system datafile forms under system maintainance, delete the subrecord defining the field. Exit ABxCD. checkdb ------- This command verifies a database, checking for internal corruption. It also zeroes all the free areas between variables and shows the location and size of free areas and variables. The compress factor is shown. compressdb ---------- This moves variables within the database in order to reduce fragmentation. As variables grow they are moved and allocated a larger space within the database file. This leaves a free area which may be re-used. When a free area is re-used often only part of it is used leaving a smaller free area. Adjacent free areas are joined into one larger free area automatically. Over time, the database will contain many small free areas rather than just a few large ones which means that when a large variable has to be moved the database file must be extended to accomodate it. The compressdb command moves five carefully selected variables in order to move the free areas together. Use the compressdb command several times until fragmentation is sufficiently reduced. As a guide to the level of fragmentation, the compress factor is shown; this is the percentage of free areas to variables; values over 50 are bad and compressdb should be run repeatedly until the compress factor goes below 10. When running interactively, if the compress factor is over 50 the system automatically performs a compress; this is done after there have have been no keypresses for two seconds. Moved 1-dimension string type variables are re-sized to allow for 25% free space and 50% unused cells. The compressdb command normally does not cause the database file to be extended but may, on rare occasions, do so. Generally, if the database file is about to be extended this is detected and a warning is issued. Also, when a database cannot be further compressed a warning is issued. These warnings appear as error numbers T32 and T33.